<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html>
<head>
<title>sprox_desfire_keys_c.html</title>
<!-- Source : c:/temp/desfire/sprox_desfire_keys.c -->
<!-- Doc generated on Thu Jun 24 12:26:36 2010 by johann on PC_DEV_5 -->
<!-- Generated with ROBODoc Version 4.99.8 (Specific build by PRO ACTIVE - Apr 13 2010) -->
<style type="text/css">
body
{
  background-color: #ffffff;
  color: #000000;
  font-family: Verdana, Geneva, Lucida, Arial, Helvetica, sans-serif;
  font-size: 9pt;
  margin-left: 60px;
  margin-right: 40px;  
}
table
{
  border-collapse: collapse;
  border-style: solid;
  border-width: 1px;
  border-color: #000000;
  margin-bottom: 12px;
}
td
{
  font-family: Verdana, Geneva, Lucida, Arial, Helvetica, sans-serif;
  font-size: 9pt;
  vertical-align: top;
  padding-right: 6px;
  border-style: solid;
  border-width: 1px;
  border-color: #dddddd; 
}
th
{
  font-family: Verdana, Geneva, Lucida, Arial, Helvetica, sans-serif;
  font-size: 9pt;
  vertical-align: top;  
  padding-right: 6px;
  border-style: solid;
  border-width: 1px;
  border-color: #000000;
  background-color: #dddddd;  
}
h1
{
  font-family: Verdana, Geneva, Lucida, Arial, Helvetica, sans-serif;
  font-size: 18pt;
  font-weight: bold;
  margin-bottom: 36px;
  color: #000000;
  margin-left: -40px;
}
h2
{
  font-family: Verdana, Geneva, Lucida, Arial, Helvetica, sans-serif;
  font-size: 12pt;
  font-weight: bold;
  margin-top: 48px;
  margin-bottom: 24px;
  padding-top: 2px;
  padding-bottom: 2px;
  background-color: #dddddd;
  color: #000000;
  margin-left: -40px;
}
h3
{
  font-family: Verdana, Geneva, Lucida, Arial, Helvetica, sans-serif;
  font-size: 11pt;
  font-weight: bold;
  margin-top: 36px;
  margin-bottom: 24px; 
  border-style: none;
  border-top-style: solid;  
  border-width: 1px;
  border-color: #cccccc; 
  margin-left: -40px;
}
h4
{
  font-family: Verdana, Geneva, Lucida, Arial, Helvetica, sans-serif;
  font-size: 11pt;
  font-weight: bold;
  margin-top: 24px;
  margin-bottom: 12px;  
}
h5
{
  font-family: Verdana, Geneva, Lucida, Arial, Helvetica, sans-serif;
  font-size: 9pt;
  font-weight: bold;
  margin-top: 12px;
  margin-bottom: 2px;  
}
a
{
  color: #0000ff;
}
p
{
  margin-top: 0px;
  margin-bottom: 6px;  
  width: 600px;
  text-align: justify;
}
ul
{
  margin-top: 0px;
  margin-bottom: 6px;  
  width: 600px;
  text-align: justify;
}
li
{
  margin-top: 0px;
  margin-bottom: 6px;  
  width: 550px;
  text-align: justify;
}
tt
{
  font-family: Courier, Courier New;
  font-size: 10pt;
}
pre
{
  background-color: #ffffff;
  color: #000000;
  font-size: 10pt;
}
.NAV
{
  font-size: 7pt;
}
a.NAV
{
  color: #0000cc;
}
.TOC
{
  font-size: 9pt;
  color: #888888;
}
a.TOC
{
  color: #0000ff;
}
.INDEX
{
  font-size: 9pt;
}
a.INDEX
{
  color: #0000ff;
}
.TYPE
{
  font-size: 7pt;
  color: #888888;
}
.ITEM
{
  font-weight: bold;
  color: #000088;
}
.LABEL
{
  color: #000088;
}
.HISTORY
{
  color: #006600;
}
.AUTHOR
{
  color: #006600;
}
.COPYRIGHT
{
  color: #006600;
}
.PORTABILITY
{
  color: #006600;
}
.WARNING
{
  color: #aa0000;
}

.bitinfo
{
  width: 60px;
  font-style: italic;
  text-align: center;
}

.bitnum
{
  text-align: center;
}

.bitname
{
  font-weight: bold;
  text-align: center;
}

.tabitem
{
  width: 100px;
}

.tabname
{
  width: 200px;
}

.tabdesc
{
  width: 450px;
}

.value
{
  font-family: courier;
  text-align: right;
}

.tabsepar
{
  border-top-style: solid;
  border-bottom-style: solid;
  border-width: 2px;
  border-color: #888888;
  font-style: italic;
  text-align: center;
}
</style>
</head>
<body bgcolor="#FFFFFF">
<a name="robo_top_of_doc"></a>
<h3 align="center">TABLE OF CONTENTS</h3>
<ul>
<li><a class="TOC" href="#robo8">Keys</a></li>
<li><a class="TOC" href="#robo30">ChangeKey</a></li>
<li><a class="TOC" href="#robo31">ChangeKey24</a></li>
<li><a class="TOC" href="#robo32">ChangeKeyAes</a></li>
<li><a class="TOC" href="#robo33">ChangeKeySettings</a></li>
<li><a class="TOC" href="#robo105">GetKeySettings</a></li>
<li><a class="TOC" href="#robo106">GetKeyVersion</a></li>
</ul>
<h3>&nbsp;</h3>


<h1><a name="robo8"><span class="TYPE">[Modules]</span><a class="LABEL" name="Keys">
Keys</a></h1>

<p class="NAV">[<a class="NAV" href="#robo_top_of_doc">top</a>][<a class="NAV" href="./modules.html#top">index</a>]</p>
<p class="ITEM">NAME</p>
<span class="NAME"><pre class="NAME">   DesfireAPI :: Key management functions
</pre>
</span><p class="ITEM">COPYRIGHT</p>
<span class="COPYRIGHT"><pre class="COPYRIGHT">   (c) 2009 SpringCard - <a href="http://www.springcard.com">www.springcard.com</a>
</pre>
</span><p class="ITEM">DESCRIPTION</p>
<span class="DESCRIPTION"><pre class="DESCRIPTION">   Implementation of management functions to change keys or
   key settings withing a DESFIRE application.
</pre>
</span>


<h2><a name="robo30"><span class="TYPE">[Functions]</span><a class="LABEL" name="ChangeKey">
ChangeKey</a></h2>

<p class="NAV">[<a class="NAV" href="#robo_top_of_doc">top</a>][<a class="NAV" href="./functions.html#top">index</a>]</p>
<p class="ITEM">NAME</p>
<span class="NAME"><pre class="NAME">   <strong>ChangeKey</strong>
</pre>
</span><p class="ITEM">DESCRIPTION</p>
<span class="DESCRIPTION"><pre class="DESCRIPTION">   Change a <a class="LINK_6" href="./sprox_desfire_des_c.html#robo5">DES</a>, or 3DES2K key in the selected Desfire application.
</pre>
</span><p class="ITEM">SYNOPSIS</p>
<span class="SYNOPSIS"><pre class="SYNOPSIS">   [[sprox_desfire.dll]]
   SWORD SPROX_Desfire_ChangeKey(BYTE key_number,
                                 const BYTE new_key[16],
                                 const BYTE old_key[16]);

   [[sprox_desfire_ex.dll]]
   SWORD SPROXx_Desfire_ChangeKey(SPROX_INSTANCE rInst,
                                  BYTE key_number,
                                  const BYTE new_key[16],
                                  const BYTE old_key[16]);

   [[pcsc_desfire.dll]]
   LONG  SCardDesfire_ChangeKey(SCARDHANDLE hCard,
                                BYTE key_number,
                                const BYTE new_key[16],
                                const BYTE old_key[16]);
</pre>
</span><p class="ITEM">INPUTS</p>
<span class="INPUTS"><pre class="INPUTS">   BYTE key_number        : number of the key (KeyNo)
   const BYTE new_key[16] : 16-byte New Key (<a class="LINK_12" href="./sprox_desfire_des_c.html#robo5">DES</a>/3DES keys)
   const BYTE old_key[16] : 16-byte Old Key (<a class="LINK_12" href="./sprox_desfire_des_c.html#robo5">DES</a>/3DES keys)                              
</pre>
</span><p class="ITEM">RETURNS</p>
<span class="RETURNS"><pre class="RETURNS">   <a class="LINK_21" href="./desfire_card_h.html#robo77">DF_OPERATION_OK</a>    : change succeeded
   Other code if internal or communication error has occured. 
</pre>
</span><p class="ITEM">NOTES</p>
<span class="NOTES"><pre class="NOTES">   Both <a class="LINK_23" href="./sprox_desfire_des_c.html#robo5">DES</a> and 3DES keys are stored in strings consisting of 16 bytes :
   * If the 2nd half of the key string is equal to the 1st half, the key is
   handled as a single <a class="LINK_23" href="./sprox_desfire_des_c.html#robo5">DES</a> key by the DesFire card.
   * If the 2nd half of the key string is NOT equal to the 1st half, the key
   is handled as a 3DES key.

   After a successful change of the key used to reach the current authentication status, this
   authentication is invalidated, an authentication with the new key is necessary for subsequent
   operations.
   
   If authentication has been performed before calling <strong>ChangeKey</strong> with the old key,
   use NULL instead of old_key.   
</pre>
</span><p class="ITEM">SEE ALSO</p>
<span class="SEE_ALSO"><pre class="SEE ALSO">   <a class="LINK_37" href="#robo31">ChangeKey24</a>
   <a class="LINK_37" href="#robo32">ChangeKeyAes</a>
   <a class="LINK_37" href="./sprox_desfire_auth_c.html#robo26">Authenticate</a>
   <a class="LINK_37" href="#robo33">ChangeKeySettings</a>
   <a class="LINK_37" href="#robo105">GetKeySettings</a>
   <a class="LINK_37" href="#robo106">GetKeyVersion</a>
</pre>
</span>


<h2><a name="robo31"><span class="TYPE">[Functions]</span><a class="LABEL" name="ChangeKey24">
ChangeKey24</a></h2>

<p class="NAV">[<a class="NAV" href="#robo_top_of_doc">top</a>][<a class="NAV" href="./functions.html#top">index</a>]</p>
<p class="ITEM">NAME</p>
<span class="NAME"><pre class="NAME">   <strong>ChangeKey24</strong>
</pre>
</span><p class="ITEM">DESCRIPTION</p>
<span class="DESCRIPTION"><pre class="DESCRIPTION">   Change a 3DES3K key in the selected Desfire application.
</pre>
</span><p class="ITEM">SYNOPSIS</p>
<span class="SYNOPSIS"><pre class="SYNOPSIS">   [[sprox_desfire.dll]]
   SWORD SPROX_Desfire_ChangeKey24(BYTE key_number,
                                   const BYTE new_key[24],
                                   const BYTE old_key[24]);

   [[sprox_desfire_ex.dll]]
   SWORD SPROXx_Desfire_ChangeKey24(SPROX_INSTANCE rInst,
                                    BYTE key_number,
                                    const BYTE new_key[24],
                                    const BYTE old_key[24]);

   [[pcsc_desfire.dll]]
   LONG  SCardDesfire_ChangeKey24(SCARDHANDLE hCard,
                                  BYTE key_number,
                                  const BYTE new_key[24],
                                  const BYTE old_key[24]);
</pre>
</span><p class="ITEM">INPUTS</p>
<span class="INPUTS"><pre class="INPUTS">   BYTE key_number        : number of the key (KeyNo)
   const BYTE new_key[24] : 24-byte New Key (3DES keys)
   const BYTE old_key[24] : 24-byte Old Key (3DES keys)                              
</pre>
</span><p class="ITEM">RETURNS</p>
<span class="RETURNS"><pre class="RETURNS">   <a class="LINK_21" href="./desfire_card_h.html#robo77">DF_OPERATION_OK</a>    : change succeeded
   Other code if internal or communication error has occured. 
</pre>
</span><p class="ITEM">SEE ALSO</p>
<span class="SEE_ALSO"><pre class="SEE ALSO">   ChangeKey16
   <a class="LINK_37" href="#robo32">ChangeKeyAes</a>
   <a class="LINK_37" href="./sprox_desfire_auth_c.html#robo26">Authenticate</a>
   <a class="LINK_37" href="#robo33">ChangeKeySettings</a>
   <a class="LINK_37" href="#robo105">GetKeySettings</a>
   <a class="LINK_37" href="#robo106">GetKeyVersion</a>
</pre>
</span>


<h2><a name="robo32"><span class="TYPE">[Functions]</span><a class="LABEL" name="ChangeKeyAes">
ChangeKeyAes</a></h2>

<p class="NAV">[<a class="NAV" href="#robo_top_of_doc">top</a>][<a class="NAV" href="./functions.html#top">index</a>]</p>
<p class="ITEM">NAME</p>
<span class="NAME"><pre class="NAME">   <strong>ChangeKeyAes</strong>
</pre>
</span><p class="ITEM">DESCRIPTION</p>
<span class="DESCRIPTION"><pre class="DESCRIPTION">   Change an <a class="LINK_6" href="./sprox_desfire_aes_c.html#robo0">AES</a> key in the selected Desfire application.
</pre>
</span><p class="ITEM">SYNOPSIS</p>
<span class="SYNOPSIS"><pre class="SYNOPSIS">   [[sprox_desfire.dll]]
   SWORD SPROX_Desfire_ChangeKeyAes(BYTE key_number,
                                    BYTE key_version,
                                    const BYTE new_key[16],
                                    const BYTE old_key[16]);

   [[sprox_desfire_ex.dll]]
   SWORD SPROXx_Desfire_ChangeKeyAes(SPROX_INSTANCE rInst,
                                     BYTE key_number,
                                     BYTE key_version,
                                     const BYTE new_key[16],
                                     const BYTE old_key[16]);

   [[pcsc_desfire.dll]]
   LONG  SCardDesfire_ChangeKeyAes(SCARDHANDLE hCard,
                                   BYTE key_number,
                                   BYTE key_version,
                                   const BYTE new_key[16],
                                   const BYTE old_key[16]);
</pre>
</span><p class="ITEM">INPUTS</p>
<span class="INPUTS"><pre class="INPUTS">   BYTE key_number        : number of the key (KeyNo)
   BYTE key_version       : version number to be stored together with the key
   const BYTE new_key[16] : 16-byte New Key (<a class="LINK_12" href="./sprox_desfire_aes_c.html#robo0">AES</a> key)
   const BYTE old_key[16] : 16-byte Old Key (<a class="LINK_12" href="./sprox_desfire_aes_c.html#robo0">AES</a> key)                              
</pre>
</span><p class="ITEM">RETURNS</p>
<span class="RETURNS"><pre class="RETURNS">   <a class="LINK_21" href="./desfire_card_h.html#robo77">DF_OPERATION_OK</a>    : change succeeded
   Other code if internal or communication error has occured. 
</pre>
</span><p class="ITEM">SEE ALSO</p>
<span class="SEE_ALSO"><pre class="SEE ALSO">   <a class="LINK_37" href="#robo30">ChangeKey</a>
   <a class="LINK_37" href="#robo31">ChangeKey24</a>
   <a class="LINK_37" href="./sprox_desfire_auth_c.html#robo26">Authenticate</a>
   <a class="LINK_37" href="#robo33">ChangeKeySettings</a>
   <a class="LINK_37" href="#robo105">GetKeySettings</a>
   <a class="LINK_37" href="#robo106">GetKeyVersion</a>
</pre>
</span>


<h2><a name="robo33"><span class="TYPE">[Functions]</span><a class="LABEL" name="ChangeKeySettings">
ChangeKeySettings</a></h2>

<p class="NAV">[<a class="NAV" href="#robo_top_of_doc">top</a>][<a class="NAV" href="./functions.html#top">index</a>]</p>
<p class="ITEM">NAME</p>
<span class="NAME"><pre class="NAME">   <strong>ChangeKeySettings</strong>
</pre>
</span><p class="ITEM">DESCRIPTION</p>
<span class="DESCRIPTION"><pre class="DESCRIPTION">   Changes the key settings of the currently selected application
   (or of card's master key if root application is selected)
</pre>
</span><p class="ITEM">SYNOPSIS</p>
<span class="SYNOPSIS"><pre class="SYNOPSIS">   [[sprox_desfire.dll]]
   SWORD SPROX_Desfire_ChangeKeySettings (BYTE key_settings);

   [[sprox_desfire_ex.dll]]
   SWORD SPROXx_Desfire_ChangeKeySettings(SPROX_INSTANCE rInst,
                                          BYTE key_settings);

   [[pcsc_desfire.dll]]
   LONG  SCardDesfire_ChangeKeySettings  (SCARDHANDLE hCard,
                                          BYTE key_settings);
</pre>
</span><p class="ITEM">INPUTS</p>
<span class="INPUTS"><pre class="INPUTS">   BYTE key_settings  : new key settings (see chapter 4.3.2 of datasheet of mifare
                        DesFire MF3ICD40 for more information)               
</pre>
</span><p class="ITEM">RETURNS</p>
<span class="RETURNS"><pre class="RETURNS">   <a class="LINK_21" href="./desfire_card_h.html#robo77">DF_OPERATION_OK</a>    : change succeeded
   Other code if internal or communication error has occured. 
</pre>
</span><p class="ITEM">SEE ALSO</p>
<span class="SEE_ALSO"><pre class="SEE ALSO">   <a class="LINK_37" href="./sprox_desfire_auth_c.html#robo26">Authenticate</a>
   <a class="LINK_37" href="#robo105">GetKeySettings</a>
   <a class="LINK_37" href="#robo30">ChangeKey</a>
   <a class="LINK_37" href="#robo106">GetKeyVersion</a>
</pre>
</span>


<h2><a name="robo105"><span class="TYPE">[Functions]</span><a class="LABEL" name="GetKeySettings">
GetKeySettings</a></h2>

<p class="NAV">[<a class="NAV" href="#robo_top_of_doc">top</a>][<a class="NAV" href="./functions.html#top">index</a>]</p>
<p class="ITEM">NAME</p>
<span class="NAME"><pre class="NAME">   <strong>GetKeySettings</strong>
</pre>
</span><p class="ITEM">DESCRIPTION</p>
<span class="DESCRIPTION"><pre class="DESCRIPTION">   Gets information on the DesFire card and application master key settings. In addition it returns
   the maximum number of keys which can be stored within the selected application.
</pre>
</span><p class="ITEM">SYNOPSIS</p>
<span class="SYNOPSIS"><pre class="SYNOPSIS">   [[sprox_desfire.dll]]
   SWORD SPROX_Desfire_GetKeySettings (BYTE *key_settings,
                                       BYTE *key_count);

   [[sprox_desfire_ex.dll]]
   SWORD SPROXx_Desfire_GetKeySettings(SPROX_INSTANCE rInst,
                                       BYTE *key_settings,
                                       BYTE *key_count);

   [[pcsc_desfire.dll]]
   LONG  SCardDesfire_GetKeySettings  (SCARDHANDLE hCard,
                                       BYTE *key_settings,
                                       BYTE *key_count);
</pre>
</span><p class="ITEM">INPUTS</p>
<span class="INPUTS"><pre class="INPUTS">   BYTE *key_settings          : master key settings (see chapter 4.3.2 of datasheet of mifare
                                 DesFire MF3ICD40 for more information)
   BYTE *key_count             : maximum number of keys           
</pre>
</span><p class="ITEM">RETURNS</p>
<span class="RETURNS"><pre class="RETURNS">   <a class="LINK_21" href="./desfire_card_h.html#robo77">DF_OPERATION_OK</a>    : operation succeeded
   Other code if internal or communication error has occured. 
</pre>
</span><p class="ITEM">SEE ALSO</p>
<span class="SEE_ALSO"><pre class="SEE ALSO">   <a class="LINK_37" href="./sprox_desfire_auth_c.html#robo26">Authenticate</a>
   <a class="LINK_37" href="#robo33">ChangeKeySettings</a>
   <a class="LINK_37" href="#robo30">ChangeKey</a>
   <a class="LINK_37" href="#robo106">GetKeyVersion</a>
</pre>
</span>


<h2><a name="robo106"><span class="TYPE">[Functions]</span><a class="LABEL" name="GetKeyVersion">
GetKeyVersion</a></h2>

<p class="NAV">[<a class="NAV" href="#robo_top_of_doc">top</a>][<a class="NAV" href="./functions.html#top">index</a>]</p>
<p class="ITEM">NAME</p>
<span class="NAME"><pre class="NAME">   <strong>GetKeyVersion</strong>
</pre>
</span><p class="ITEM">DESCRIPTION</p>
<span class="DESCRIPTION"><pre class="DESCRIPTION">   Reads out the current key version of any key stored on the PICC
</pre>
</span><p class="ITEM">SYNOPSIS</p>
<span class="SYNOPSIS"><pre class="SYNOPSIS">   [[sprox_desfire.dll]]
   SWORD SPROX_Desfire_GetKeyVersion(BYTE bKeyNumber,
                                     BYTE *pbKeyVersion);

   [[sprox_desfire_ex.dll]]
   SWORD SPROXx_Desfire_GetKeyVersion(SPROX_INSTANCE rInst,
                                      BYTE bKeyNumber,
                                      BYTE *pbKeyVersion);

   [[pcsc_desfire.dll]]
   LONG  SCardDesfire_GetKeyVersion(SCARDHANDLE hCard,
                                    BYTE bKeyNumber,
                                    BYTE *pbKeyVersion);
</pre>
</span><p class="ITEM">INPUTS</p>
<span class="INPUTS"><pre class="INPUTS">   BYTE bKeyNumber             : number of the key (KeyNo)
   BYTE *pbKeyVersion          : current version of the specified key
</pre>
</span><p class="ITEM">RETURNS</p>
<span class="RETURNS"><pre class="RETURNS">   <a class="LINK_21" href="./desfire_card_h.html#robo77">DF_OPERATION_OK</a>    : operation succeeded
   Other code if internal or communication error has occured. 
</pre>
</span><p class="ITEM">NOTES</p>
<span class="NOTES"><pre class="NOTES">   This command can be issued without valid authentication.
</pre>
</span><p class="ITEM">SEE ALSO</p>
<span class="SEE_ALSO"><pre class="SEE ALSO">   <a class="LINK_37" href="./sprox_desfire_auth_c.html#robo26">Authenticate</a>
   <a class="LINK_37" href="#robo105">GetKeySettings</a>
   <a class="LINK_37" href="#robo33">ChangeKeySettings</a>
   <a class="LINK_37" href="#robo30">ChangeKey</a>
</pre>
</span>
<hr />
Generated from <b>sprox_desfire_keys.c</b> on Thu Jun 24 12:26:36 2010<br />
</body>
</html>
